#Domino Designer
標記為 #Domino Designer · 29 篇文章
- @SetEnvironment 與 SetEnvironmentVar：那些「環境變數」其實是寫在執行那台的 notes.ini
想從 Formula 或 LotusScript 記一個設定值，@SetEnvironment／@Environment／session.SetEnvironmentVar／GetEnvironmentString 一堆長得像。它們讀寫的其實是「執行程式那台機器的 notes.ini」——per-machine、不共享、也不複寫。加上一個容易絆倒人的 $ 前綴規則（Formula 與 LS 預設會替你加 $、讀 notes.ini 原生設定要另外處理）。這篇把它們寫到哪、$ 怎麼來、什麼時候該用、什麼時候該改用 profile 文件講清楚。
2026.09.22 - 未讀標記的坑：它是「每個使用者各一份」，不是文件的屬性
文件變粗體、旁邊那顆星號——未讀標記看起來像文件的一個欄位，其實不是。它是 Domino 少數「每個使用者各自一份」的東西：你讀了不代表別人讀了。用 LotusScript 的 MarkRead／MarkUnread 動它時很容易替錯人（agent 以某個 ID 跑，只動到那個 ID 的未讀）；而且未讀標記預設不隨複寫同步，所以 server 上和你本機 replica 的未讀狀態常常對不上。這篇把未讀的機制與三個坑講清楚。
2026.09.21 - XPages 存檔衝突：為什麼「只有你一個人」還會跳存檔衝突
「Document has been saved by another user」——奇怪的是根本沒別人在動這份文件，存檔衝突卻偶爾自己冒出來。這篇講一個 XPages 老坑：在同一份文件上混用 dominoDocument 資料來源的存檔與後端 Document 的存檔，會讓 Domino 的衝突判定誤判、生出一份 conflict 文件。從官方的衝突機制（$Revisions）講起、拆解 assono 那個經典重現，並在 Domino 12.0.2 與 14.5.1 各自實測看這個 2013 年的坑現在還在不在。
2026.09.16 - NotesView AutoUpdate=False：迴圈裡改文件為什麼越跑越慢、還跳「Entry not found in index」
一個 agent 迴圈跑 view、順手改文件，結果越跑越慢，甚至偶爾拋「Entry not found in index」。罪魁是 NotesView 預設會自動刷新：當你的迴圈改動的正是這個 view 索引的文件，view 就在你腳下一直重整，效能爛掉、導覽位置也可能失效。解法一行——迴圈前 view.AutoUpdate = False。這篇講清楚機制、正確的「先抓下一個再改」寫法，以及三個要知道的副作用（快照、只管當前程式、要 Refresh 才看得到更新）。
2026.09.15 - NoteID、UNID、@DocumentUniqueID：Domino 文件的三個 ID 到底差在哪
要指涉一份 Domino 文件，你可能會抓 NoteID、UniversalID（UNID），或在 Formula 用 @DocumentUniqueID——三個長得像、行為卻天差地遠。NoteID 只在單一資料庫檔內有意義、換個 replica 就變了；UNID 是 32 字元、跨所有 replica 都一樣的真身分；@DocumentUniqueID 回的就是 UNID（但不加 @Text 會變成 doclink）。這篇把三者的範圍、穩定性、該用哪個講清楚，含「改 UNID 會變新文件」「存重複 UNID 噴 4000」等雷，以及 web URL 那個 /0/UNID 的由來。
2026.09.14 - XPages 附件多選批次刪除：官方只能一次刪一個，自己補上「勾選多個、存檔一次刪」
XPages 的 File Download 控制項只給你一列一個、一次刪一個附件，沒有「勾選多個、一次刪」的原生做法——連做得很完整的生產表單也缺這塊。這篇先實測澄清一件事：原生刪除其實是「存檔才生效」、很守規矩；再用同樣 save-bounded 的官方 API（NotesXspDocument.removeAttachment）自己補上多選批次刪，在測試環境（Domino 12.0.2）做出一個可勾選、可反悔、存檔一次落地的實作。
2026.09.13 - XPages 檔案上傳失效：xspupload 暫存夾被 Windows cleanmgr 清掉的根源與解法（含 14.0 修復）
XPages 的檔案上傳控制項按了沒反應、使用者端沒錯誤、server console 卻報 IOFileUploadException「The system cannot find the path specified」。根源是 Domino 上傳用的暫存夾 xspupload 不見了——常常是 Windows 的磁碟清理 cleanmgr 在 Domino 執行中把它連同 temp 檔一起清掉。這篇把官方 KB 與實務串起來：症狀與根源、暫存夾為什麼會消失、以及從「每晚上下 http」這種 band-aid 到 notes_tempdir、程式化檢查重建、升級 14.0（defect 已修）的幾種解法。
2026.09.12 - 傳統 Domino web 附件 UI 的眉角：用 $V2AttachmentOptions 藏掉陽春預設，自己畫下載清單與刪除
在 Domino web form 放個 File Upload Control、加個儲存鈕，功能是通了——但畫面很陽春：附件被 Domino 倒在頁尾、編輯時還多出一排沒法美化的「標記要刪除」勾選框。這篇講傳統 Domino web 開發者的老手法：用 $V2AttachmentOptions="0" 把預設附件區藏掉、用 passthru HTML 配 @AttachmentNames 自己畫下載清單、以及那個很少人講清楚的刪除機制 %%Detach（自訂勾選框、或走 WebQuerySave）。含 $V2AttachmentOptions 只有 0/1、文字不是數字等踩雷點。
2026.09.11 - Domino 多檔上傳與依條件刪附件：傳統 web、XPages 14.5.1
上一篇講怎麼在三種情境各附一個檔；這篇進到「一次很多個」：傳統 web form 靠 HTML5 的 multiple 屬性一次選多檔、XPages 到 14.5.1 才終於預設支援多選（在那之前是 OpenNTF 社群方案的天下），以及實務上最常遇到、參考卻最少的「依條件挑著刪」——迭代 EmbeddedObjects、依 .Source 檔名條件逐一 Remove（附可照跑範例）。附一張圖說明多選的檔怎麼落到同一個富文本欄位。
2026.09.09 - Domino 附件的三種上傳法：Notes client、傳統 web form、XPages
在 Notes client 附一個檔案，把它拖進富文本欄位就好，簡單到不像個功能。但同樣的需求搬到 web、或搬進 XPages，「怎麼讓使用者上傳檔案」就變成三個不同的答案：client 靠富文本欄位、傳統 web form 用 File Upload Control 這個內嵌元素、XPages 用 xp:fileUpload 搭 xp:fileDownload。這篇把三種前端上傳機制擺在一起對照，並點出讓人安心的一件事——三者最後都落在文件的同一個富文本欄位裡，所以後端撈檔、抽取、刪除的程式碼是共用的。
2026.09.08 - 跨 DB 的 embedded view 搬到測試區就「無法啟動」？問題出在 DXL 裡綁死的抄本 ID
一個 form 上的跨 DB 嵌入視圖，在開發區好好的，交到客戶測試區就顯示「無法啟動」。翻遍 Designer 的嵌入視圖 UI 也沒有地方換來源資料庫。把 form 匯出成 DXL 才發現：embeddedview 元素用來源庫的抄本 ID（replica ID）綁死來源，換了環境那個 ID 就對不上。這篇是實測記錄：怎麼診斷、怎麼用一支 NotesDXLExporter/Importer 的 agent 批次換掉，以及後來才發現的更快解法——Designer 直接「以 DXL 編輯」。
2026.08.18 - 你的 Domino view 表頭為什麼永遠歪一格：passthrough HTML 黑魔法考古
接手一個老 classic-web Domino view，你常會發現直欄標題整體往右偏一格 —— 而且沒人知道為什麼。一篇實測報告，挖出藏在二十年前 view 設計裡的 passthrough HTML 把戲：直欄值與標題裡的方括號 HTML、間隔欄、每列 checkbox，以及真正的元兇 —— 一個故意不閉合的 <input 標籤吞掉 </td><td> 欄界線、把兩個直欄合併成一格，讓它之後的每個表頭都往右偏。
2026.07.22 - 多層分類 view 裡的 GetAllDocumentsByKey：為什麼你的 count 悄悄就錯了
在單層分類 view，GetAllDocumentsByKey('Belgien', True) 正確回傳那個分類下的 2 筆文件。但加上第二層分類 — Form 再 Country — GetAllDocumentsByKey('Customer', True) 回傳 3，不是全部。它停在第一個子分類就不走了。本文記錄這個實測驗證過的陷阱與繞法。
2026.07.09 - NSF ODP Tooling：不開 Designer，把 NSF 變成可版控的原始碼
NSF ODP Tooling 是 OpenNTF 的專案，把二進位的 NSF 拆成檔案系統上的 On-Disk Project（ODP），讓你能把 Domino 應用放進 Git，再不靠 Domino Designer 就把 ODP 編譯回完整的 NSF —— 為 Domino 帶來真正的版本控制與 CI/CD。本文完整介紹它是什麼、Maven plugin 與容器化編譯怎麼運作，以及 4.1.0 這一版實際改了什麼。
2026.06.27 - NotesOutline / NotesOutlineEntry 全攻略 — Domino UI 導覽控件的程式化建構、4 種 entry type、24 個 property
NotesOutline 是 Domino 應用程式的左側 / 上方導覽控件，由 NotesOutlineEntry 條目以樹狀組成。透過 LotusScript 可以動態建立、修改、走訪 outline — 典型 use case 是多語切換（依 user locale 動態改 Label）、條件式 menu（依 role 顯示／隱藏）、動態使用者連結。本文整理 NotesOutline ↔ NotesOutlineEntry 關係、8 個 tree-walking 方法、6 個 manipulation 方法、24 個 entry property、4 個 Set* 方法、4 種 entry type 常數、9 個 EntryClass 常數、完整 CRUD 範例、五個踩雷點，跟 Java / SSJS 對照。
2026.05.20 - LotusScript 解析 XML 該選 DOM 還是 SAX — 五個問題決定走哪邊
LotusScript 處理 XML 有三條路：NotesDOMParser（整棵樹載入）、NotesSAXParser（事件驅動串流）、NotesXMLProcessor + NotesXSLTransformer（XSLT 規則式轉換）。本文整理三家本質差異對照、五個決策問題（檔案大小 / 是否修改 / 走訪方向 / 記憶體限制 / 轉換場景）、實務情境的選擇建議，附程式碼風格對照、效能比較跟踩雷集錦。讀完知道 LS 拿到一份 XML 該怎麼開動。
2026.05.18 - NotesDOMParser 全攻略 — XML 整棵樹載入記憶體、14 個 Node 類別、走訪／修改／序列化
NotesDOMParser 把 XML 整棵載入記憶體蓋成 DOM 樹、用 NotesDOMDocumentNode 當 root、配 14 個 Node 子類別代表不同 XML 元素（Element / Text / Attribute / Comment / CDATA 等）。可任意走訪、可修改、可 Serialize 回 XML。本文整理 DOM 樹結構概念、CreateDOMParser 初始化、14 個 Node class 關係表、NotesDOMNode 的 tree-walking API（FirstChild / NextSibling / NodeType）、完整 parse → walk → modify → serialize 範例、五個踩雷點，跟 Java/SSJS 對照。
2026.05.17 - NotesSAXParser 全攻略 — LotusScript 串流式 XML 解析、12 個 SAX 事件、On Event 綁定模式
NotesSAXParser 用 SAX（Simple API for XML）事件驅動模式處理 XML — 不把整份檔案載入記憶體、而是邊讀邊觸發 SAX_StartElement / SAX_Characters / SAX_EndElement 等 12 個事件。大檔案 / 只讀特定 element / 記憶體吃緊場景的首選。本文整理 SAX vs DOM 的本質差異、CreateSAXParser 初始化、On Event 綁定機制、12 個事件的觸發時機、NotesSAXAttributeList 怎麼拿 attribute、完整 LotusScript 範例、五個踩雷點，跟 Java / SSJS 對照。
2026.05.16 - NotesSession 全攻略 — LotusScript 的入口、單例規則、UserName 的三個變體、Evaluate 把 @Formula 拉進 LS
NotesSession 是每支 LotusScript 一定會碰到的入口 class — 它代表「當前 script 的執行環境」，提供 CurrentDatabase、UserName / EffectiveUserName / CommonUserName 三個 user 屬性、Evaluate 從 LS 跑 @Formula、CreateLog 寫 NotesLog、GetEnvironmentString 讀 notes.ini。本文整理 class 角色、一個 script 一個 session 的規則、核心 property / method、UserName 三變體在 On Behalf Of agent 的差異、server 端 vs client 端存取權限差異、五個踩雷點，跟完整範例。
2026.05.14 - NotesDocument 全攻略 — LotusScript 最核心類別的拿到、CRUD、五個踩雷點
NotesDocument 是 LotusScript 操作 Domino 文件最核心的類別 — 但它的細節很容易踩雷：GetItemValue 永遠回陣列、Save 的三個參數中 createResponse 常被誤解、Remove 的 force 不是軟刪除開關（軟刪除是 DB 層設定，要永久刪用 RemovePermanently）、direct property 跟 ReplaceItemValue 的微妙差別、漏 Save 是最常見的 silent bug。本文整理拿到 NotesDocument 的所有途徑、Item / Field 的觀念、CRUD 範例、五個必懂的坑、sibling methods 跟 Java/SSJS 對照。
2026.05.13 - NotesView.GetAllDocumentsByKey 全攻略：你以為簡單，但它有五個踩雷點
GetAllDocumentsByKey 是 LotusScript 開發中最常用的查詢方法 —— 給一個 key、拿回符合的所有 doc。但「key 對應 sorted column 不是 doc field」「exactMatch 預設 False 是前綴比對」「反斜線分類欄位讓查詢失效」這些細節，HCL 官方文件寫了但很多人沒讀完。本文整理 signature、整個 by-key 方法家族、五個常見踩雷點，附完整範例。
2026.05.09 - LotusScript 的對外 HTTP / JSON 工具鏈：NotesHTTPRequest + NotesJSONNavigator
Domino V12 起 LotusScript 內建 NotesHTTPRequest 跟 NotesJSONNavigator 兩個 class，可以直接從 LS 打外部 REST API 拿 JSON 回來解析 — 不再需要 ActiveX 或 shell 出去呼叫 curl。本文整理兩個 class 的 method、屬性、PreferJSONNavigator 把兩者串起來的官方途徑、完整範例，跟 Java / SSJS 的對位差異。
2026.05.07 - NotesXMLProcessor 入門：LotusScript 處理 XML 的共同基底
NotesXMLProcessor 是 LotusScript 全部 XML 處理類別（DOMParser、SAXParser、DXLExporter、DXLImporter、XSLTransformer）共用的 abstract base class。本文整理它的角色、5 個衍生類別怎麼選、共通的屬性與 SetInput / SetOutput / Process 三個方法、以及 Release 6 起加入後的版本與 COM 限制。
2026.05.06 - DQL Production-Ready：Catalog 維運、權限、與 sessionAsSigner
把 DQL 上 production 真正會撞牆的兩個問題：Design Catalog 怎麼自動維護（包含全新 NSF 的 bootstrap、設計變更後的 incremental refresh），以及為什麼一般使用者跑會噴「您沒有權限執行此作業」——以及對應的 sessionAsSigner / scheduled agent 解法。本文整理實測 Domino 12 驗證過的最終 pattern + Java production-ready 範例。
2026.05.03 - LotusScript NotesStream 實戰指南：把檔案讀寫做對
NotesStream 是 LotusScript 從 Notes/Domino 代理人讀寫檔案的標準抽象。本文整理 Open 真正的 signature、Truncate-before-write 的寫入慣例、文字與二進位 I/O 的差異，以及官方文件實際載明的陷阱。
2026.05.02 - DQL 踩雷集：寫 query 時 6 個官方文件不會明說的細節
Domino Query Language（DQL）的語法表面像 SQL，但實戰起來有一整套 Notes 特有的踩雷點 —— view selection 會默默限縮結果範圍、`'view'.column` 的 column 不是文件欄位名而是直欄程式名稱、比較運算子兩邊要空白、view 名稱含反斜線要 escape、`@formula` 內是獨立的 Formula Language parser、字串日期欄位要 `@TextToTime`。本篇用實測錯誤訊息對照逐個說明。
2026.05.01 - NotesRichTextItem 入門：用 LotusScript 操作富文本欄位
NotesRichTextItem（富文本項目）繼承自 NotesItem，所以 NotesItem 的全部屬性與方法都能用；但它另外有 22 個專屬方法處理段落、樣式、表格、嵌入物件、Navigator/Range 進階遍歷。本文整理建立方式、22 個方法分類、繼承關係，與寫程式時常踩的雷。
2026.04.30 - NotesNoteCollection 入門：操作 NSF 設計元素的瑞士刀
NotesNoteCollection（筆記集合）跟 NotesDocumentCollection 不同，它代表的是 NSF 裡所有「note」—— 包含資料文件、表單、視圖、ACL、代理程式、程式庫等設計元素。本文整理 32 個屬性、14 個方法、CreateNoteCollection 的 True/False 兩種起始模式，以及最常用的場景：DXL 匯出。
2026.04.29 - NotesViewNavigator 入門：用導航器走視圖，不要再 GetFirstDocument 硬撈
NotesViewNavigator（視圖導航器）是 LotusScript 走視圖的進階工具：能拿到 ViewEntry（視圖條目，含類別、總計、位置等視圖才有的中介資料）、能從子集合（單一類別、未讀、某層以下）建立、效能上比 GetFirstDocument 迴圈高，但使用之前要先把 AutoUpdate 關掉。本文整理 4 個屬性、約 36 個方法、7 個 CreateViewNav* 變體與重要注意事項。
2026.04.29